| « A sneak peek on b2evo v5 | Exciting times... » |
Planning for a new Manual
The b2evolution User Manual has been following a rocky path all these years.
Our latest attempt was to sort of crowdsource the Manual by using a Wiki platform to run it. This resulted in many tips & tricks pages, a lot of spam pages... and not a lot of core documentation.
Well, we are going to put the manual back in the hands of the developers. And out goes the Wiki, which is really not that convenient to use for editing anyways. This doesn't mean, though, that there is no space for user input. As a matter of fact, the new manual will be based on a b2evolution blog (which gives us 100% control on how we want to deal with spam) and each page will have a comments section.
We plan to run this a little bit like the PHP Manual... which has user comments... but they are heavily moderated and edited for clarity... so that the signal to noise ratio can stay as high as possible. (Unmoderated speach is available in the Forums).
One aspect where the PHP Manual falls a little short still... is the structured chapter navigation. Well it's not as bad as the Wiki which has no chapters and no structure at all, but still, it's a bit difficult to know exactly where you are in the PHP manual... you know approximatelty but you're never sure if you're at the last level or not.
So we are developing a "manual skin" inspired by the PHP manual but with a little bit more visual cues as to were we are.
There are 2 mockups attached to this post. One shows what happens when you are browsing through chapters & sub-chapters. The other shows what happens when you reached a manual page.
If you have thoughts about this, please send us your feedback below so we can adjust our target if need be.
...
This entry was posted on September 6th, 2012 at 11:47:00 pm by François and is filed under State of the Evolution.
2 comments
Was about time..I hope it will be kept as simple as possible.. I dont fancy a lot of people would be keen to learn a lot of [short_code] and {fancy-tag} mumbo-jumbo like wiki's, i mean i would not.
Regular users could only write so much as they know, which would be far from sufficient.And we dont have many of them anyway.
We need main developers, the ones who exactly know what they are writing, (especially you) to step in i guess.
Writing documents is always a pain in the a** i know.Sometimes it may take an hour to write about a code which might have took 15 minutes to actually create it.
BUT, you write it once, and hundreds benefit, if not thousands, which will only make it better and easier as more people are capable of chipping in, both code & manual-wise.
Users won't have to learn any tags as they won't write any manual page. They will be able to leave comments but we'll reformat them for them. We will also try to answer their questions by writing new manual pages, as long as the questions are of general purpose and not situation specific technical support.
Comment feed for this post