Gitea: Improve the documentation

[pgaskin]

I think the documentation needs to be redone.

Reasons:

• The current documentation is inconsistent
• The current documentation focuses on installation and configuration
  
  
  
  • It should have more tutorials, user guides, and other useful things
  
  
• It is hard to find things (no search)
• It is very unstructured and will not work well with many pages
• The current documentation lacks important things which are useful when installing and using gitea
• The current method of viewing the documentation will become hard to use once we have many pages
• And more which I cannot remember

What I have started to work on

• I have started working on this issue on my git server: https://git.geek1011.net/geek1011/gitea-stuff
• The viewer is here: https://git.geek1011.net/geek1011/gitea-stuff/raw/master/index.html
• If anyone wants to help, just tell me, and I will create an account for you on my server.
  
  
  
  • Help would be nice on the viewer; see the todos at the bottom of the source code
  
  
  • Most of the help is needed on writing documentation for the user guides
  
  
  • I want to do most of the admin documentation, I have quite a bit of experience with it
  
  

Also, before I do too much on this, I want to know if the @go-gitea/maintainers and the @go-gitea/owners agree with what I am doing. Also, if anyone has any comments on this, I would like to hear.

A note related to the current documentation: My documentation will be static, it will not need hugo to generate it.

[lunny]

All the latest document is generated by Hugo. And this one ?

[pgaskin]

@lunny It's a static page which uses AJAX to load a JSON-based index and the page content. Have a look at the code on my server.

[lunny]

Since Gitea is a community product, we should use the almost popular technical so that many people could contribute for her.

[pgaskin]

@lunny sorry, but what do you mean by the almost popular technical?

[pgaskin]

If you mean technologies, I think my method is better than hugo, because hugo has it's limits. I am using popular libraries such as jquery and semantic ui though.

Have a look at my code. It's pretty easy to understand and it will end up as only about 200-400 lines.

[appleboy]

@geek1011 How to translate to other languages?

[tboerger]

Ajax to load the index? Pretty bad for search engine indexing...

[tboerger]

And I don't share your opinion that your technology is better than Hugo. Hugo generates a really static website which can be indexed and search engine optimized.

[pgaskin]

@tboerger @mjwwit @lunny As for my viewer for the docs, it can be made static, but I would prefer Jekyll or a custom script, unless someone else does Hugo. It should be pretty easy to render the docs as completely static pages. Myiewer is not done yet though. Also, my layout makes it easy to switch: it's the pattern Category/Section/Page Title.md. I will continue the docs, but someone else can put together a better site. I just hacked something together quickly to test my docs.

[pgaskin]

And for SEO, it is fine, once I put routing in.

[pgaskin]

Also, @tboerger I never said it was better than Hugo, I said I didn't like Hugo. This could probably be easily made into a static site with almost any generator.

[andreynering]

@geek1011 Hugo is what most of the team knows. Also, Gitea being written in Go, we give preference for Go tools, and Jekyll uses Ruby. Hugo is also more used for new sites than Jekyll, today.

Improvements to documentation are very welcome! But let's keep our currently tooling that is more than fine. Current docs is at: https://github.com/go-gitea/docs

[pgaskin]

@andreynering ok, your first point is fine. About the existing docs, they need a restructure. IMO, there should be admin docs, user docs, and dev docs. Inside each category, there should be a section, which contains pages.

[andreynering]

there should be admin docs, user docs, and dev docs. Inside each category, there should be a section, which contains pages.

That makes sense to me.

[pgaskin]

I will learn hugo today, and switch it over. 😃

[pgaskin]

And a relevant article I came across: https://thenextweb.com/dd/2017/06/02/free-software-is-suffering-because-coders-dont-know-how-to-write-documentation/

[sondr3]

If anything I'd like to help write some documentation, but not really sure where to begin, is there some kind of list we could compile for documentation that needs to be written?