I need help reorganizing the Wiki
-
@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.
