Please enable the github wiki for the project

[julie777]

Describe your use-case

A good place for development documentation, planning releases, even user tips would be a wiki.

Describe the solution you would like to see for your use-case

Please enable the wiki for the pyscaffold project.

[abravalheri]

Hi @julie777, thank you very much for bringing this discussion forward.

Can you elaborate what are the biggest advantages of enabling the wiki vs using a section on the website + github discussions?

[julie777]

Discussions are a transitory thing. They are very useful and valid at the time. The problem is they are less useful when you want to see what was decided a year later.

Website is not dynamic. You can't change it right now. You can't add a comment about something. You can't add a note. You can't reword something that is hard to understand.

The easy of change reduces the impedance to documenting things. It is so easy to take 5 minutes to write down something you think might be useful to others. And, you don't have to be sure it really is useful. Parts of the wiki can be what amounts to shared notes.

Currently I am in a strong learning phase. I am discovering things, asking questions, making personal notes. Let's assume that I develop a good understand of some part of the code that hasn't been touched in a long time, is a little complicated, and seems unnecessarily hard to change. While I was learning about it I took notes and eventually came to what I believe is an understanding of it.

Now with a wiki, before I move on to the next task, I review my notes and add a quick page to the wiki outlining what I discovered about how it works and interacts with the rest of the system. Possibly you read it a few days later and correct a couple things and add a little bit more that your learned.

Over time we gain a better understanding of the entire system and a new contributor can easily take advantage of that knowledge.

@abravalheri I just notice that you are adding labels such as "needs discussion". Thank you. I had not thought of that. I will do better in the future.

[FlorianWilhelm]

Hm..., good points @julie777. So you would rather see the Wiki as an internal tool for maintainers to document and layout design decisions in one compact place?

From a user's perspective, we should make sure that our docs are really well and users find what they are looking for effortless. @abravalheri has done an awesome job over the last years to improve our RTD Sphinx docs and for instance our FAQ section I find really helpful. Thus our users should have a single contact point, i.e. pyscaffold.org, when they are looking for general information about PyScaffold.

For new contributors, there is right now the Developer's guide. and I use it as a reference quite often. Would you suggest moving this then over to the Wiki? Or is the Wiki more for notes and when they are gold, they then go into the Sphinx docs?

Do you have an example project where this works? I would like to understand more.

[julie777]

As a part of some other research, this morning I carefully read the single contributing page.

This is not to be taken as criticism

1. It is very pretty.
2. It shows how much power sphinx has for formatting and layout.
3. It covers multiple topics and would be more focused as multiple pages with cross-linking.
4. I found several errors that I would have corrected instantly if it was a wiki.
5. There is one part, that just by being part of the page adds another level of confusion.

As I said before, I don't know if github wiki has all the power of the other wikis that I have used, but I will look into it.

I'm going to do an experiment today and then share it with you. Stay tuned 😄

Aside --
Since pyscaffold has its own domain instead of using readthedocs.io do we have the ability to host applications there, or is it just for serving web pages?

[julie777]

Hi @julie777, thank you very much for bringing this discussion forward.

Can you elaborate what are the biggest advantages of enabling the wiki vs using a section on the website + github discussions?

After much writing and thinking this morning, I realized that my first response to your question should have been

Have you ever used a wiki?

which would have given me the information I needed to properly provide more information. So I am asking it now.

@abravalheri @FlorianWilhelm
Have you ever used a wiki?

[abravalheri]

Yes I did 😆, and I am also aware about the limitations of the Guthub wiki and the capabilities of using GitHub GUI also to suggest changes for documents that are not on a wiki.

(Yes I admit the current docs no longer have a "edit on github" button like the old ones had after the change on the template, but maybe that can be addressed?)

[FlorianWilhelm]

Good question @julie777, I have used even Redmine in the old days and countless other Wikis I have even forgotten the names of. Currently, I am forced to use Confluence at work, which at least doesn't completely suck, to be blunt. On the other hand, I must say that I just love Markdown as it is so simple and gets the job done. I also like that the docs are really closely tight the source code. If I would add a new feature to PyScaffold on a dev branch I could also already change the docs accordingly which is not possible with a Wiki.

[julie777]

@abravalheri @FlorianWilhelm
What do you think of as the pros and cons of using a wiki for some types of documentation? Feel free to comment differently based on type.

[FlorianWilhelm]

The biggest plus of a wiki is that you can edit easily. But as @abravalheri mentioned this is also possible by just clicking the Markdown file's edit button in the Github API (if it is only for something small like a typo). For bigger doc changes I quite like that our current process uses PR, so we can all look at the changes and then it gets merged like code changes. Again the big plus that docs and code are coupled. Also using the Github Wiki would make us depend on Github forever. At the moment I like Github a lot but what if Microsoft starts charging OSS for it in the future? Then we would move maybe to Gitlab and moving the Wiki could be a real pain. I like things to be independent as much as possible and Markdown really is. Thanks to Sphinx it basically just renders to HTML and we can use any service we want, right now RTD, to show it.

@julie777 What kind of docs would you want to see in the Wiki?

[julie777]

Well, I did take a look at the edit the doc button. I will admit it is easier than a full code change pull request, unless I missed something someone that wants to make a change still has to clone the repo and submit the pull request. It just make it easy to open the file to edit in an editor.

I don't think that compares with just clicking edit, changing a couple characters and clicking save.

I find the dynamic nature of the wiki compelling for developer documentation. No publishing required. Everyone can see it right away.

As for the thoughts about tying us to github, I don't believe that is true at all. Given that github stores the wiki in a repo that we control, we can move those files to another wiki hosted somewhere else if we decide to do so. In addition the Github wiki does use markdown. They allow editing in other formats, but it seems to all end up as GitHub markdown.

I realize that the Github wiki has some missing features. The haven't added quick links to issues and discussions yet. I found a few more things that I was used to that didn't exist. (I started working on a demo wiki with part of our doc just to see how easy it was. My first big realization was that organizing some of it a little differently was easy to try out. And, links to other pages, or any URL is so easy that I found myself being very free with linking. I didn't get to a point where I wanted to say "hey look at this". Instead, I just allocated a certain amount of time and stopped working on it. It is part of my fork of the pyscaffold repo if you want to look at it.

The idea of reviewing docs with a formal pull request sounds pretty reasonable to me for user documentation. We really want to make that a good experience for the user. User doc should also coincide with project releases so that it matches what is available to use. Developer docs can have ideas that didn't pan out, or a history of why we did certain things. With freedom to just write stuff down information will be captured that will never make it into a formal doc.

Well, enough evangelizing for tonight.

BTW, who is paying for our domain?
Are we hosting our docs on readthedocs.io using our domain?

[FlorianWilhelm]

Let's discuss the wiki topic next Sunday then when we meet. We could give the wiki a try although I am still quite skeptical. Since @abravalheri wrote the current pages for developers in Markdown (and I really like them), I think foremost you need to convince him of the wiki.

Yes, we host our docs on RTD (which is for free for OSS) and I pay for the domain pyscaffold.org (1.40 € per month) which forwards to the IP of RTD using DNS record and Cloudflare. Every year or so this breaks when the IP of RTD suddenly changes. I haven't found a better solution that also supports HTTPS.

[abravalheri]

I think I have accidentally added my thoughts to the discussion in #604 (comment) 😅.

Let's talk about that next weekend!

---

Just a small note:

Currently the dev docs are written in rst for the PyScaffold repository, although there is a port in pyscaffoldext-markdown. However I think the debate mardown x rst is not relevant to this particular topic since this can be easily changed both directions.