I need help reorganizing the Wiki
-
Looking at the Wiki lately, I'm seeing a lot of pages in the sidebar. This is great as it provides a lot of information right away to newcomers, but it's getting a little ridiculous. I mean, look at what happens on mobile! There are also pages from before the Canonical drop that are getting stale and should be removed or refreshed.
The solution to this is to reorganize the wiki. Here's my proposal. I need your help. Check the bottom of this post for the current topic of discussion for this thread and a direct link to where the discussion starts.
Goal
Make navigation on the Wiki easier by reorganizing pages into categories and refreshing stale information.
We will also be switching to Read the Docs for better readability, navigation, and source control. We have officially outgrown Jingo.
Currently proposed category scheme
- About (About UBports, documentation structure)
- User Guides
- Installation
- Daily Use
- Hacking (Fancy command line stuff, things that require writable root)
- Contribution
- Bug Reporting
- App Development
- OS Development
- Translation
- Documentation
- Monetary Support
Steps to Success
- Finish this proposal (Important step!)
- Fix stale pages
a. Identify pages that are more than ~4 months old
b. Determine if the information in them is relevant
c. Refresh or delete as needed - Land the docs
a. Create landing pages for each category in selected category scheme. Landing pages describe and link to the correct pages for the category.
b. Rewrite lame homepage to correctly introduce the categories - Reorganize!
a. Place the landing pages in the sidebar
b. Place the landing pages on the website under the correct "Get Involved" header - Going forward
a. Assign members to keep sections of the documentation fresh
b. Set up some kind of alerting to find when pages have become stale (Haven't been updated in a while)
And finally, the future goal of the documentation team:
Analyze our common hurdles to contributing. Document the process of getting over these. Place them in the correct category.Current topic of discussion:
While we work on refreshing the documents, do we want to write them in md for the wiki or just use rst and go straight to RTD? I suggest we use rst and start committing to RTD so we can bring it up faster.
-
I think you are right planning to reorganize the wiki. I think I will help if you like.
Your sheme is the more logical solution as far as I can say. Anyway, I would add a section like "Daily Use" or something like that, oriented to non-developer users where is explained how to use non-obvious features of ubuntu touch (like for example the already existent guides about CalDav and Libertine). Maybe that is supposed to be the "Documentation" section? -
@UniSuperBox your proposal seems pretty sensible, and a good starting point.
Anyhow I miss in it:
- A clear reference to "Installation" because that's the first thing the newbies look for.
- Also a FAQ about the project is usually pretty convenient.
- A code of conduct for the UBports community and how to participate & help.
- All the legal stuff.
- How to collaborate to the wiki.
There goes your summer
-
@Emanuele-Sorce Aha! I knew I forgot something. That'll be a great place for things like "Installation" and other guides for new users as @advocatux mentioned. I'll add that to the proposed categories.
@advocatux I like all of these ideas, some of them are already covered.
- User documentation is definitely needed.
- The FAQ can be found on the website. Did you have another idea for it?
- Code of Conduct is important!
- All the legal stuff? Can you give some examples?
- How to contribute to the wiki would go in the category made for the Documentation team.
-
@UniSuperBox, as it's now there are links to the wiki, and links in the wiki to external sources v.g the Halium documentation. The FAQ could be linked that way, no problem.
When I say legal stuff I mean things like a description of UBports Foundation, but also privacy (v.g. related to the data people give to UBports), or what kind of app is illegal or not wanted in the store, or what kind of licenses for apps, or what license for publishing in the wiki, or what people can or can't do with UBports intellectual property (like logos, or if color pattern or whatever if going to be registered then that too, etc), or how must be described and presented a unofficial app and what kind of logo can use (hint: not an official logo without the rights to use it, like is happening now), etc.
-
Hi, first of all, great idea! I will try to contribute some time to this effort if i can.
About the structure: To keep it even tidier, the last five bullet points ("Language/Translation" up to "Design") might all fit the major category contributing perhaps? (Although Development is contributing too, any idea how we could differentiate between those two types of contribution and still keep it to 3 main categories? First [lame] idea is Other contribution, Non-Coding Contribution, ...?)
-
Thanks for your proposal! I think it is an important one. Actually a bit overdue
Let's get to it - I am very willing to help.With respect to the structure: I definitely agree with remarks that Installation should be a top link. And I think the titles should be short. taking into account the comments so far, what about this proposal:
- Installation
- Documentation
(Daily use, CalDAV configuration, Libertine, FAQ, etc.) - Contribution
- Get in touch
(Telegram, IRC, Website, community updates) - App Development
- OS Development
(Halium, porting guide, Middle of stack. content-hub, Yunit, etc., Drivers n' stuff Infrastructure ) - Bug reporting
- Translation
- Documentation
(encourage people to collaborate in the wiki) - Support us
(Patreon, paypal)
- Get in touch
- About us
(Code of Conduct - I'm not aware there exist one?!, legal stuff)
Some of the items I lumped together (Infrastructure, Drivers) correct me if that doesn't make sense. I probably didn't really understand what you meant there.
Some more items, I dropped entirely. Maybe just lack of imagination, but I don't see any Design, Marketing or QA content yet in the wiki, nor do I have obvious ideas of what and why this should be added now. But if we have valuable content or create it then let's add these categories. I think 5 to 10 links in the side bar would make for a reasonable navigation structure (I only have four
)On another note: A good resource to draw content from is this German wiki: https://wiki.ubuntuusers.de/Ubuntu_Touch/ . I contributed there, thus I know some parts quite well and could transfer/rewrite them without too much effort.
Edit: small update after checking the current state of the wiki sidebar
-
@doniks said in I need help reorganizing the Wiki:
A good resource to draw content from is this German wiki: https://wiki.ubuntuusers.de/Ubuntu_Touch/
That would be great. There are some really interesting hints and solutions.
-
@Bastos said in I need help reorganizing the Wiki:
@doniks said in I need help reorganizing the Wiki:
A good resource to draw content from is this German wiki: https://wiki.ubuntuusers.de/Ubuntu_Touch/
That would be great. There are some really interesting hints and solutions.
Is there a specific topic you think about?
-
After thinking on this for a while, I agree that a slimmer sidebar is probably in order if we stay with Jingo.
With increased work on the Wiki, though, there have also been discussions of trying out Read the Docs. We've been seeing the cracks of Jingo for a while, and they're starting to become noticeable as we continue to grow. We were hit with vandalism for the first time about a week ago, which wasn't pleasant. Otherwise,, all of the known limitations are biting us.
I say that we start to go forward with building up Read the Docs as a replacement for the Jingo wiki, with the plan being to replace the Wiki after we've got the "Install" documentation moved over and the general structure in place. You can find our RTD repository here. It's already being built and served here.
I'll also update the proposed structure in the OP.
-
@UniSuperBox said in I need help reorganizing the Wiki:
With increased work on the Wiki, though, there have also been discussions of trying out Read the Docs. We've been seeing the cracks of Jingo for a while, and they're starting to become noticeable as we continue to grow. We were hit with vandalism for the first time about a week ago, which wasn't pleasant. Otherwise,, all of the known limitations are biting us.
Sorry to hear you had a hard time with vandalism. I don't know RTD well, but doesn't that complicate contribution a lot. Maybe I'm mistaken, but my best guess would be that the workflow with RTD would be:
- I fork the repository on github (need an account)
- make a branch for the proposed edit I want to do
- check that branch out locally
- edit locally in some texteditor
- create a pull request
- someone with sufficient rights reviews and (after my followup if needed) merges
That is a quite significantly larger hurdle than a wiki edit.
I'll also update the proposed structure in the OP.
Looks good to me now!
The only thing I might still consider is making the Installation even more prominently. I imagine that many first time visitors are not even looking for the basic what is it? They know already on a high level, otherwise they wouldn't be here. What they want to know now is how to get it?
-
@doniks said in I need help reorganizing the Wiki:
but my best guess would be that the workflow with RTD would be:
It's actually not that hard to do. Read the Docs provides a handy "Edit on Github" link that brings you to a page where you can fork the repository, make your edits, then create a Pull Request. Try it on our Read The Docs page! Just Click the pull-up menu in the lower left and select "Edit".
-
Talk about the use of Libertine.
-
@UniSuperBox said in I need help reorganizing the Wiki:
It's actually not that hard to do. Read the Docs provides a handy "Edit on Github" link that brings you to a page where you can fork the repository, make your edits, then create a Pull Request. Try it on our Read The Docs page! Just Click the pull-up menu in the lower left and select "Edit".
Ah, ok. That's better than I feared! Made a small PR.
No buttons though that help me with stuff like code-blocks, image insertion, inline-code, headings, numbered list, etc.
-
@doniks said in I need help reorganizing the Wiki:
No buttons though that help me with stuff like code-blocks,
No, unfortunately, those aren't available. However, depending on whether we go with rst or md (Markdown is easier to write, ReStructuredText works way better with Read the Docs), there are plenty of available editors that can be used.
Edit: I think we're in agreement regarding the structure of the new documents. Now, let's get what we already have up to date. Tomorrow I'll post a list of all documents in the wiki that are more than 4 months old so we can take them on.
Would you all like if I created a Telegram group for more realtime communications as we enter this phase?
I've also updated the current discussion topic. While we work on refreshing the documents, do we want to write them in Markdown for the wiki or just use ReStructuredText and go straight to Read The Docs?
-
@UniSuperBox
If we are going to move to ReadTheDoc and remove the current wiki, I think is better to go with ReStructuredText straight to RTD. -
Edit: I think we're in agreement regarding the structure of the new documents.
Yes.
Would you all like if I created a Telegram group for more realtime communications as we enter this phase?
Well, uhm, I know, I might be the odd-one-out here, but personally, I linger in forums, irc and email. But I see that the defacto standard for much of ubports communication is telegram. So, uhhh, yeah, whatever works for people....
Now, let's get what we already have up to date. Tomorrow I'll post a list of all documents in the wiki that are more than 4 months old so we can take them on.
I've also updated the current discussion topic. While we work on refreshing the documents, do we want to write them in Markdown for the wiki or just use ReStructuredText and go straight to Read The Docs?
I'm a bit lost here. "While we work on" sounds like you propose that we update pages in the wiki. While "go straight to Read The Docs" sounds like the opposite, so there wouldn't be any "While" right?! So if your question is: Should we update first and then migrate, or migrate right away? Then I'd say: Migrate right away! Edit: Let me clarify this. I'd say migrate if it has been decided that we move to RTD. I don't know any of: wiki software, RTD, markdown, restructuredtext good enough to have a strong opinion about the choice of technology.
Also I'm not sure how the migration of existing content would work. Manually? Copy/paste/rewrite? Just asking.
Lastly, to your point about the 4 months or older. I don't think age is a very useful metric. Some pages might be very old but not in need for an update or the opposite: very recently changed and still very wrong. But taking one more step back, I would anyway pull apart the process management for right now for this reorganization project and the management of updating (and/or extending) the documentation in the future.
For this reorganization project I'd say a manually maintained priority list of pages in RTD would be good enough. It's not like there is thousands of pages in the wiki.
-
Yes.
Great!
personally, I linger in forums, irc and email. But I see that the defacto standard for much of ubports communication is telegram.
I see. I'll start tracking our progress on GitHub, we'll see if we hit any pain from there.
"While we work on" sounds like you propose that we update pages in the wiki. While "go straight to Read The Docs" sounds like the opposite, so there wouldn't be any "While" right?!
That's exactly correct. If you vote to move to RDT, I'm completely in agreement with you. Let's do that, the wiki is in an acceptable state until we complete.
I don't think age is a very useful metric.
You're right, but it's a good starting point as Canonical dropped the project four months ago. Some things are different after we took over.
I would anyway pull apart the process management for right now for this reorganization project and the management of updating (and/or extending) the documentation in the future.
I like it. Take this one step at a time.
Also I'm not sure how the migration of existing content would work. Manually? Copy/paste/rewrite?
Shoving the Markdown directly into ReadTheDocs would work since our setup supports both ReStructuredText and MD. However, RST works much better with RTD so it's best to reformat the pages.
So, I'll get some issues cooked up in the docs repository so we can start.
-
@UniSuperBox said in I need help reorganizing the Wiki:
I don't think age is a very useful metric.
You're right, but it's a good starting point as Canonical dropped the project four months ago. Some things are different after we took over.
Ah ... 4 months ... now I get it
I like it. Take this one step at a time.
Also I'm not sure how the migration of existing content would work. Manually? Copy/paste/rewrite?
Shoving the Markdown directly into ReadTheDocs would work since our setup supports both ReStructuredText and MD. However, RST works much better with RTD so it's best to reformat the pages.
ok.
if I may utter one wish: it would help me if someone could clobber together a quick draft for the Contribution/Documentation page. Otherwise, I need to go figuring it out for myself. workflow (editing on github or local, when/whennot), RST syntax reference, editor, testing.
So, I'll get some issues cooked up in the docs repository so we can start.
thanks
-
@doniks said in I need help reorganizing the Wiki:
if I may utter one wish: it would help me if someone could clobber together a quick draft for the Contribution/Documentation page. Otherwise, I need to go figuring it out for myself. workflow (editing on github or local, when/whennot), RST syntax reference, editor, testing.
