documentation at source{d}

[campoy]

No description provided.

[campoy]

This is a first draft of the document on how to write documentation at source{d}
Please review and let me know what you all think.

[smeruelo]

Actually Grace Hopper never had children. Let's try also not to assume any woman is a mom ;)

[campoy]

good point! replaced mothers with women
thanks :)

[erizocosmico]

since there's probably a lot of common practices, would it be useful to have a standard org-wide CONTRIBUTING.md just ready to copy and paste for all new projects?

[erizocosmico]

Nvm, we have it: https://github.com/src-d/guide/blob/master/engineering/documents/CONTRIBUTING.md. Still think it'd be useful to mention it here, though.

[campoy]

I wonder if we should copy it around on every repo or simply link to it?
It seems a bit dangerous to simply copy things around in every repo tbh

What do you think, @mcuadros ?

[dpordomingo]

I don't like copy things, but I was told that's the standard way.
Anyhow, I see two different parts in the CONTRIBUTING.md

• general contributing guidelines, that could be linked or copied everywhere,
• project instructions, like how to develop, run tests, run in development or even how to develop... that we sometimes put in the CONTRIBUTING.md instead of in the README.md

[mcuadros]

The contributing file has custom parts, maybe half of it, so you need to having it on the repo. You can link to a more regeneral stuff, but at the end what I saw in other orgs, is that just simply copy the file, since doesn't change to much during the time.

[campoy]

I added a reference to that file and added also a Template field on the reference section below.

[erizocosmico]

I think it'd be useful here to have a block of markdown you can just copy and paste in a README with the "we have a CoC and it's yada yada yada" and a link to the specific text (https://www.contributor-covenant.org/version/1/4/code-of-conduct.md)

[campoy]

done
also added .github/CODE_OF_CONDUCT.md as per https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/

[mcuadros]

And also maybe a script, docker or something should be provided.

[campoy]

great point, yes
done

[mcuadros]

Following this guide, please include a link to semantive versioning principles. :D

[campoy]

done

[mcuadros]

True, but sometime expensive, its a realistic objetive?

[campoy]

I think it's not necessarily expensive. The notes are not exhaustive. Basically what's in the release that I might care about.

[mcuadros]

A template will be great to have more homogoneus files, the same with CONTRIBUTING.md.

[campoy]

I created one under documents

[mcuadros]

Excellent guide. Congratulations @campoy

[mcuadros]

The issues are part of the articacts, include the templates. We need to document how to handle an issue, and also define a template or at least the rules to create one.

[campoy]

Are we using issue templates anywhere already?
I know of them through github.com/golang/go

[dpordomingo]

Infra does it, and I love it
https://github.com/src-d/issues-infrastructure/issues/new

[bzz]

DR does at some projects https://github.com/src-d/engine/blob/master/ISSUE_TEMPLATE.md

[mcuadros]

Also, I wantted to include here, about how create documentation from an issue, but maybe this is not the place.

[campoy]

cool, I added a section on this too!

[bzz]

Do you think it might be useful to include some actual examples of .md syntax with the badges, so people can just update it, instead of opening some other project and copying from there?

[mcuadros]

Sure thing.

[campoy]

Good idea! I added a couple of examples taken from go-git

[bzz]

Guys after reading README template, I have few questions:

1. Do we really expect to have Example of utilization section or do we expect each project to re-phrase it to something like Usage or Run, etc?
2. As a developer, I find it very useful when readme includes a section on Development with at least a high-level description on how to build/test the project. As many of our projects are for developers, do you think it might be worth adding such thing near to the end? (With many be a link to CONTRIBUTING.md for excessive details)
3. As a user, I find it very useful to have a Quickstart of TL;DR style of section that describes main usage in few lines, so a fist-time users can copy and run them immediately to accommodate their goal of trying out new things very quickly, before spending more time on reading/exploring it. Would that be something useful to have?
4. One more thing that I find really useful - explicit statement about pre-requisites or runtime dependencies or assumptions about environement that the project has in order to be operational. Ideally those would have been incapsulated in Docker images, so a commands to start DB, a Queue, a Bblfsh, etc might be given, or, at worst, links to each dependency documentation can be provided. So user does not need to discover this though trail and errors, on trying to kickstart the process. What do you think?

[bzz]

s/most of you/most of us/ ?

Otherwise, together with I, might be perceived as a little bit.. well, alienating.
What do you think?

[campoy]

Good point! 😄
done

[vmarkovtsev]

What is the difference between "believe in" and "believe on"?

[campoy]

apparently one believes on god, but in other things ... so fixed

[vmarkovtsev]

How does it play with Golang? go-git.v4 spans for one year :)

[mcuadros]

This was following the semvers, since you had the RCs, but yes, wasn't a good example of semver

[mcuadros]

Also maybe we can provid guides for format, like witch headers, should be used.

[campoy]

I think the headers that appear on this list are the ones I'd like people to use

# Project Name being the first one

[mcuadros]

For some langauages we should define the style of the examples, for example in go, the example should be from a extnernal point of view (good), or for a internal point of view of the library (bad). Because some example doesn't include the package name for the symbols of the package on the example, because are code from a example in the package, and then you can't copy paste it.

[campoy]

added

[dpordomingo]

Wow! you did an awesome work (we needed it a lot), thanks!

Since we're trying to improve the documentation and our projects itself, and having a homogeneous structure benefits the developer experience (as I could understand from comment#r160391444), why not offering a project skeleton. I think it would ensure that all our projects follow our requirements?

I'd suggest:

engineering/project-skeleton/
├── .github
│   ├── CODE_OF_CONDUCT.md
│   ├── CONTRIBUTING.tpl.md
│   ├── ISSUE_TEMPLATE
│   └── PULL_REQUEST_TEMPLATE
├── DCO
├── LICENSE.apache
├── LICENSE.gpl
├── MAINTAINERS
└── README.tmpl.md

[dpordomingo]

Is this an example to follow? It seems it does not follow your template, nor sections.
What if we link to one of our README?
(example: https://github.com/src-d/go-git/blob/master/README.md)

[campoy]

This is not an example, this is a quick reference for README.md
Every kind of document has one.

[dpordomingo]

I don't like copy things, but I was told that's the standard way.
Anyhow, I see two different parts in the CONTRIBUTING.md

• general contributing guidelines, that could be linked or copied everywhere,
• project instructions, like how to develop, run tests, run in development or even how to develop... that we sometimes put in the CONTRIBUTING.md instead of in the README.md

[dpordomingo]

I'd link here a template, as you did in the README section
documents/CONTRIBUTING.md

[dpordomingo]

links to a [README.md]; anyhow: what if we link one of ours?
(example: https://github.com/bblfsh/dashboard/blob/master/CONTRIBUTING.md)

[campoy]

Added a link to the CONTRIBUTING.md in the guide

[dpordomingo]

For apps having visual interface, it would be useful to have a screenshot (like in bblfsh/dashboard) or a recorded cli session (as in sqle/gitquery)

[campoy]

added

[dpordomingo]

I wonder if the filter applied really worths; could it be only the link to the issues tab?

[campoy]

True, I got this from go-git but I don't have strong feelings about it.
I'll remove it.

[dpordomingo]

Our first CONTRIBUTING.md didn't include info about how to develop, run tests... and I didn't expect to find that info over there. I think it makes sense to put such info in the CONTRIBUTING.md but we should maybe say so in the README.md to inform our visitors (as we tried at snippet-search or bblfsh/dashboard)

[bzz]

This was one of the questions I tried to rise in #84 (comment) as well

[campoy]

Each project is different, but yes, it is part of the things CONTRIBUTING.md should cover (as mentioned in documentation.md)

[dpordomingo]

Since this is proposed as a template, I'd add our two options for licenses, and a link to the guide/engineering/licensing.md#licence

• GPL v3.0, for core parts
• Apache License 2.0, for libraries/tools that intended to be consumed by third-parties

[campoy]

added

[dpordomingo]

This doc is huge with a lot of useful resources.
Do you think a TOC would help the reader what can be found here?
I see the following:

• General Best Practices
  • State a clear goal
  • Define a scope
  • Don't alienate the reader
  • Take accessibility in mind
• Documentation Artifacts
  • README.md
  • CONTRIBUTING.md
  • Reference material
  • Release Notes
  • Issues, PullRequests, Improvement Proposals...
  • Guides/Tutorials
  • Code of Conduct
  • Other pieces documentation
• Resources

[campoy]

Yeah, I'm happy to add the TOC once the content has been agreed on.

[ricardobaeta]

@campoy I'll comment further on this matter, nevertheless, one classic accessibility best practice is to avoid having links like: "you can find something here" or "more about something" or even "download the latest something". The reason is because a common use-case for visual-impair people is to use screen-readers in a way to go over links, and as you have probably guessed what they will hear will be here, more and download without context. So I would recommend to shorten links but be as explicit/descriptive as possible. You can read more about descriptivelinks here.

[ricardobaeta]

@campoy There are images that are complex to describe with an alt attribute, like some data visualisations. We can aim - maybe @dpordomingo can help how to do this in markdown - to make complex images as usable and accessible as possible. There are some techniques to improve accessibility on complex images.

[campoy]

Yeah, that's why I say "at least". An alt attribute doesn't solve the problem but at least can tell the reader whether the image is relevant or just a logo.

[campoy]

OK, I sent a bunch of updates and I feel this starts to look quite decent!

Thanks all for your help 👍

[dpordomingo]

As I said, it looks great to me.
(there are some things that could be improved, but since it can be proposed/studied via issues, I'll not block the merge because of that)

[eiso]

Approving because all relevant comments (that were on my mind) have been mentioned already and I see they're being incorporated in the doc.

[eiso]

@bzz just want to give a +1 on your 4 points, especially on the quick start section (minor feedback @bzz, if you make your general review a comment on a line; it's not as clean, but easier to have a threaded discussion).

[campoy]

+1 on having comments in line, it's easy to miss the comments made in the conversation

[campoy]

Adding comment from @bzz here to keep track of it

Guys after reading README template, I have few questions:

1. Do we really expect to have Example of utilization section or do we expect each project to re-phrase it to something like Usage or Run, etc?

2. As a developer, I find it very useful when readme includes a section on Development with at least a high-level description on how to build/test the project. As many of our projects are for developers, do you think it might be worth adding such thing near to the end? (With many be a link to CONTRIBUTING.md for excessive details)

3. As a user, I find it very useful to have a Quickstart of TL;DR style of section that describes main usage in few lines, so a fist-time users can copy and run them immediately to accommodate their goal of trying out new things very quickly, before spending more time on reading/exploring it. Would that be something useful to have?

4. One more thing that I find really useful - explicit statement about pre-requisites or runtime dependencies or assumptions about environement that the project has in order to be operational. Ideally those would have been incapsulated in Docker images, so a commands to start DB, a Queue, a Bblfsh, etc might be given, or, at worst, links to each dependency documentation can be provided. So user does not need to discover this though trail and errors, on trying to kickstart the process. What do you think?

[campoy]

Thanks for your points @bzz!

1. I think "Example of utilization" is good, but not necessarily the best. So up to the maintainer of the project to use whatever they feel like.

2. I think the build/test instructions could be part of the "Example of utilization" section if it's simple enough. If not I'd probably simply have a link to "building from source code". Most people will use Docker or aptitude packages when available.

3. This is exactly the kind of context I expect to see in the "Example of utilization" for tools. Something like make build; cmd foo bar

4. I would expect these requirements to be part of the installation instructions yeah. See line 46 for this. Maybe I should make it more obvious?

[bzz]

2. Sounds great. Do you think it may be worth to articulate that somehow in there that it's acceptable to have short build commands in that section?

3. From my experience, indeed it's totally worth to go extra mile here and make it painfully obvious

[campoy]

Applied @bzz's feedback. I think I just need @mcuadros's approval to be able to merge

[eiso]

Glad to see this merged, can you please make a PR to the README with a link (and possibly add a README to the documentation folder with a ToC to these files)

[campoy]

There you have it: #96