I need help reorganizing the Wiki

doniks · 8 Mar 2017, 18:17

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)
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

Bastos · 4 Aug 2017, 09:56

@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.

doniks · 8 May 2017, 07:52

@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?

UniSuperBox · 5 Aug 2017, 16:34

@doniks

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.

doniks · 5 Aug 2017, 18:03

@UniSuperBox said in I need help reorganizing the Wiki:

@doniks

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?

UniSuperBox · 5 Aug 2017, 19:26

@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".

Cesar Herrera · 5 Aug 2017, 19:37

Talk about the use of Libertine.

doniks · 7 Aug 2017, 09:02

@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.

UniSuperBox · 8 Aug 2017, 01:53

@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?

Emanuele Sorce · 8 Aug 2017, 09:03

@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.

doniks · 8 Aug 2017, 19:29

@UniSuperBox

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.

UniSuperBox · 8 Aug 2017, 23:26

@doniks

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.

doniks · 9 Aug 2017, 05:57

@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

UniSuperBox · 11 Aug 2017, 00:53

@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.

Ask and you shall receive.

doniks · 11 Aug 2017, 05:51

@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.

Ask and you shall receive.

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.

UniSuperBox · 11 Aug 2017, 14:00

@doniks

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.

UniSuperBox · 19 Aug 2017, 00:43

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!

NeoTheThird · 20 Aug 2017, 08:56

@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.