I need help reorganizing the Wiki
-
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.
-
@UniSuperBox said in I need help reorganizing the Wiki:
@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.
Nice thanks!
Seems to have one inconsistency: contribute-doc-intro vs contribute-doc-index. Can you check that?
I think similarly the link on the startpage http://docsubportscom.readthedocs.io/en/latest/index.html
to "introduction" doesn't work. -
Thanks for pointing those out. I've fixed the inconsistencies and generally made the site work better.
Fun fact: Sphinx won't build a page if it doesn't have a heading.
-
Quick update: @NeoTheThird has been working on getting some App Development documentation into the site. I've also added a new section to the contribute page that helps building it locally, no guesswork needed.
The User Guide is the place that will need the most love immediately while contribution items can lag a bit. If you have a page in the wiki that you really want in the docs, now would be a perfect time to bring it in!
-
@UniSuperBox said in I need help reorganizing the Wiki:
@NeoTheThird has been working on getting some App Development
It's very rough yet and much of it is outdated, but if someone is interested in fixing some broken links or update some content, knock yourself out
I'm not territorial about this.
