One of our next goals for improving the article pages is to try to communicate their structure better to our visitors. To do this I need to give The Brigade a clear idea of what our page structure is.
So… what’s our page structure? Do we have a common structure we use for references? Is it the same or different between CSS/HTML/JS/APIs/Extentions? Do we have a common structure we use for tutorials and guides?
I think many of you are experts in certain areas, you should chime in with what you know and I’ll make sure it gets to Brigade in a coherent format.
So, we have a pretty standard structure that we strongly encourage but don’t always enforce right now. Sometimes we need to fudge it a little when an API is quirky in some way. And of course much of our older content hasn’t been updated to use the new structures, which I would love for us to have time to attend to but we haven’t as yet.
If you need skeleton versions of pages, I can get those together for you (I need to do them anyway). I don’t know if that’s what you’re after though.
Not all pages exactly follow this structure, but most are close to it. One major difference is that just about all the existing pages have a “See also” H2, and I’d like us to consider using some alternative nav for this kind of thing.
[WIP] I’m working on this gist to provide info about the structures used across the HTML/CSS and JavaScript sections (Reference).
Some of it is already redundant with what @wbamberg added and parts are yet to be filled.
There is also the property table for CSS pages. Is the suggestion that we remove that? If not, I’d at least move it to the bottom of the page and collapse it by default.
The gist contains what I’ve been able to collect for HTML/CSS/JavaScript reference before the deadline.
This is a bit rushed/drafty but provides info regarding the structure for different categories of pages.
By no means this is supposed to be a “normative” document, many pages will be a bit different from the “common” structure I tried to get. This gist would actually be more helpful to create new pages respecting those templates rather than wanting to update every page which would “just be a bit different”.
@fscholz : /I’ll complete with the other “classes” of pages for JS later on./ Done @sheppy : I hope you can find this useful for the overall meta-structure-documentation @wbamberg : some verification on CSS would be welcome