Wiki style, organization and guidelines
Posted: Fri Nov 12, 2021 6:09 am
Hi everyone,
Recently, when reading the wiki, i wanted to add information to incomplete pages or modify some areas, but i wondered about "wiki style".
I'd like to raise 3 issues i see in the wiki right now :
- The wiki has no defined style, unlike for example wikipedia (encyclopedic tone)
This leads to radically different pages, the easiest example being tutorial pages vs encyclopedia pages (for ex: Multiprocessing is encyclopedic whereas SMP really looks like a tutorial, and bare bones and such are really tutorial pages)
Don't get me wrong, i don't think there shouldn't be tutorials on the Wiki, but me might want to add a "page category" or something to show which pages are tutorials and which pages are more like encyclopedic articles. This way, we could for example remove tutorial links on the Main Page, and provide them in the associated "encyclopedic" page (this is actually the case i think, but tutorials are referenced as "see also" and not in a precise "tutorial articles" category...)
I don't think the wiki is bad the way it is right now, but i believe that it is hard to expand, and defining guidelines on how to write articles as well as trying to organize them better would help on that matter.
- This leads to another issue, that i will illustrate with an example. I've been intersted in U-Boot recently, so i read the OSDev Wiki article. As you can see, it is completely empty for now except for a wikipedia link. I read the wikipedia article, and then i wondered : should i copy the basic information (what is U-Boot, where it is used, ...) from there or even the whole article (citing the source of course) ? I don't think so, as OSDev should not contain either historical elements, why was it developed ; just a basic description and then technical information. Then i read U-Boot specification and i wondered : should i copy the useful information to the wiki ? But then is the wiki just a simpler version of the specification ? That isn't really useful then, the page ARM Paging is like that and i always end up reading the ARM ARM instead...
I think the guidelines for writing articles should define parts needed for articles : a part of description, a part of "official specifications"/memory layouts/..., a part of how to implement it, what's hard about it/... and finally links to tutorial pages. (but that's my first idea, feel free to comment on that)
- Finally, one last issue, a point that i think might help begginers but prevents extension of the wiki : the wiki is centered on x86, specifically i386 (or x86_32), in 2 ways : default version of articles target x86 (for example Paging is x86 Paging and ARM Paging is for ARM) (this is comprehensible and can stay this way) and some pages on doing stuff that should be architecture-independant mentions the specifics of x86 (instead of having another article "x86 - feature", which would allow the creation of other articles like "ARMv6 - feature" )
For example, i think the Paging page should only present the global concept of paging in virtual memory, and link to (for now) two articles x86 Paging and ARM Paging.
This way we could add Paging for every architecture without having to describe what is paging in every ARCH-Paging article and just referencing it on the Paging one.
Anyway, i don't think the wiki is bad the way it is now, but as i said before, i believe fixing those 3 issues would allow the creation of new pages and the extension of current ones without going everywhere without a direction thus creating a monster.
Maybe there are already such rules on the wiki, but i couldn't find them... Either those are implicit and we should write an article about it or the article exists and it should be linked to the main page with the "contributing" articles.
Maybe this issue has already been discussed, but there is no pinned post on the board or mention of it in the "contributing" sections of the wiki, so i didn't find it.
Maybe the community doesn't share my opinion, and prefers to be able to do anything they want on the wiki ; to me, we should leave that possibility to user articles.
Anyway, i'd like to hear your comments on this, and maybe together we can, if we agree, define wiki articles guidelines.
The idea is not to change every article in existence but to impose guidelines to new articles so that they are futureproof and maybe along the way improving current ones so that they follow guidelines.
Those guidelines would not be inflexible rules but more of an help to structure an article and all.
(I apologize if my english isn't very good, i'm not a native speaker)
vhaudiquet
Recently, when reading the wiki, i wanted to add information to incomplete pages or modify some areas, but i wondered about "wiki style".
I'd like to raise 3 issues i see in the wiki right now :
- The wiki has no defined style, unlike for example wikipedia (encyclopedic tone)
This leads to radically different pages, the easiest example being tutorial pages vs encyclopedia pages (for ex: Multiprocessing is encyclopedic whereas SMP really looks like a tutorial, and bare bones and such are really tutorial pages)
Don't get me wrong, i don't think there shouldn't be tutorials on the Wiki, but me might want to add a "page category" or something to show which pages are tutorials and which pages are more like encyclopedic articles. This way, we could for example remove tutorial links on the Main Page, and provide them in the associated "encyclopedic" page (this is actually the case i think, but tutorials are referenced as "see also" and not in a precise "tutorial articles" category...)
I don't think the wiki is bad the way it is right now, but i believe that it is hard to expand, and defining guidelines on how to write articles as well as trying to organize them better would help on that matter.
- This leads to another issue, that i will illustrate with an example. I've been intersted in U-Boot recently, so i read the OSDev Wiki article. As you can see, it is completely empty for now except for a wikipedia link. I read the wikipedia article, and then i wondered : should i copy the basic information (what is U-Boot, where it is used, ...) from there or even the whole article (citing the source of course) ? I don't think so, as OSDev should not contain either historical elements, why was it developed ; just a basic description and then technical information. Then i read U-Boot specification and i wondered : should i copy the useful information to the wiki ? But then is the wiki just a simpler version of the specification ? That isn't really useful then, the page ARM Paging is like that and i always end up reading the ARM ARM instead...
I think the guidelines for writing articles should define parts needed for articles : a part of description, a part of "official specifications"/memory layouts/..., a part of how to implement it, what's hard about it/... and finally links to tutorial pages. (but that's my first idea, feel free to comment on that)
- Finally, one last issue, a point that i think might help begginers but prevents extension of the wiki : the wiki is centered on x86, specifically i386 (or x86_32), in 2 ways : default version of articles target x86 (for example Paging is x86 Paging and ARM Paging is for ARM) (this is comprehensible and can stay this way) and some pages on doing stuff that should be architecture-independant mentions the specifics of x86 (instead of having another article "x86 - feature", which would allow the creation of other articles like "ARMv6 - feature" )
For example, i think the Paging page should only present the global concept of paging in virtual memory, and link to (for now) two articles x86 Paging and ARM Paging.
This way we could add Paging for every architecture without having to describe what is paging in every ARCH-Paging article and just referencing it on the Paging one.
Anyway, i don't think the wiki is bad the way it is now, but as i said before, i believe fixing those 3 issues would allow the creation of new pages and the extension of current ones without going everywhere without a direction thus creating a monster.
Maybe there are already such rules on the wiki, but i couldn't find them... Either those are implicit and we should write an article about it or the article exists and it should be linked to the main page with the "contributing" articles.
Maybe this issue has already been discussed, but there is no pinned post on the board or mention of it in the "contributing" sections of the wiki, so i didn't find it.
Maybe the community doesn't share my opinion, and prefers to be able to do anything they want on the wiki ; to me, we should leave that possibility to user articles.
Anyway, i'd like to hear your comments on this, and maybe together we can, if we agree, define wiki articles guidelines.
The idea is not to change every article in existence but to impose guidelines to new articles so that they are futureproof and maybe along the way improving current ones so that they follow guidelines.
Those guidelines would not be inflexible rules but more of an help to structure an article and all.
(I apologize if my english isn't very good, i'm not a native speaker)
vhaudiquet