Feature Request #1916
Proposal to improve the formatting, structure and content of Kohana Projects
|Assignee:||Woody Gilk||% Done:|
|Category:||Kohana Website/Server||Estimated time:||1.00 hour|
At present, the Projects Wiki is difficult to read due to the body CSS, and probably less that 25% of projects have any wiki documentation. Of those, only a few have anything near approaching complete documentation due mainly to the difficulty / lack of knowledge in writing and structuring.
I propose that this be tackled in 3 stages:
1. Update the CSS to make the content readable
2. Write a Wiki Documentation 101 giving project creators a head start in documenting
3. Use the Documentor project to encourage people to write quality documentation offline then convert it online.
For the first stage, I've spent a fair amount of time crafting an updated set of styles and a demonstration suite that show how it works, and how it could be a lot clearer.
It comes in 2 parts:
1. An Introduction showing the general design and formatting decisions
2. Examples, with the option to toggle styles between before and after.
Implementation is as simple as adding the stylesheet reference to the main application.css file.
Once implemented, I can finish off Documentor and it should be fairly trivial to get a Kohana Project Docmentation 101 written.
I'd like to take this opportunity to say I'd like to officially offer my time to get more involved with the web / documentation side of things if required.
#1 Updated by Oscar Bajner over 4 years ago
Dave, would you please attach your patch (wiki.css) directly to this ticket.
Do I understand correctly, the stylesheet may be applied without affecting the existing wiki layout, but to take affect, some small changes to the page markup is required?
I don't see any reason why this proposal should be turned down.
#2 Updated by Dave Stewart over 4 years ago
- File wiki.css added
That's great news!
No changes to the markup are needed; what I've done is to implement some CSS combinations that result in modified formatting that should be advantageous to the reader.
For example, using b tags inside H3 tags will turn the tagged text red (whereas otherwise the bold tags would have had no effect on already bold text). This could be useful for things like making method namss stand out when documenting a long list of class methods.
The new stylesheet is attached. As I said, I think I've tested it as fully as possible, but if it has any ill effects in once you're done, I'll fix and re-update this request.
#5 Updated by Dave Stewart over 4 years ago
Controversial one this I suppose.
"!important" may not need to be in there (maybe I had to override it?), but I set the html to scroll so that when you go from a short page to a long page, or vice versa, you don't get an annoying shift to the left or right of all the content as the scroll bars come up.
A lot of the projects pages are of varying length, so it makes sense I think.
(The scroll track will display benignly all the time, and the bar will only show when the page is long enough)