Certbot: Documentation cleanup!

[pde]

We have documentation in too many places. Let's clean up and deprecate them!

Ones we want to keep:

• reStructuredText in this repo (and on readthedocs.org), in three main sections:
  
  
  
  • including the introduction (README.rst in the top level)
  
  
  • a using.rst "user guide" (is probably too redundant with the introduction...)
  
  
  • a contributing.rst "developer guide"
  
  
• the instruction generator that lives in certbot/website
• FAQs on the Certbot website.

Ones we want to get rid of:

• the wiki on this repo
• distinctly worded material at https://letsencrypt.org/getting-started

Ones that are in the middle:

• docs that are on community.letsencrypt.org

[pde]

Also the command-line help from the client, which is mostly generated in this file

[pde]

@ptychomancer is organizing this cleanup effort with his colleagues at Salesforce...

[SwartzCr]

Wiki!
References in the docs:
https://github.com/certbot/certbot/blame/master/docs/ciphers.rst#L159
https://github.com/certbot/certbot/blame/master/docs/contributing.rst#L326
https://github.com/certbot/certbot/blame/master/docs/using.rst#L197
https://github.com/certbot/certbot/blame/master/docs/using.rst#L393
https://github.com/certbot/certbot/blame/master/docs/packaging.rst#L6
via

swartzcr@SAMIZDAT:~/Documents/coding/letsencrypt$ ag github.com/letsencrypt/letsencrypt/wiki
docs/ciphers.rst
159:https://github.com/letsencrypt/letsencrypt/wiki/Ciphersuite-guidance

docs/contributing.rst
326:  https://github.com/letsencrypt/letsencrypt/wiki/Known-issues

docs/using.rst
197:https://github.com/letsencrypt/letsencrypt/wiki/Plugins. If you're
393:manually. https://github.com/letsencrypt/letsencrypt/wiki/Ciphersuite-guidance

docs/packaging.rst
6:https://github.com/letsencrypt/letsencrypt/wiki/Packaging.

I'd say that https://github.com/certbot/certbot/wiki/Ciphersuite-guidance should be retained somewhere as it came from public comments submitted to us and should still be available even if the wiki is gone
https://github.com/certbot/certbot/wiki/Documentation can be removed as it's replaced by the rsts
https://github.com/certbot/certbot/wiki/Known-Issues can be removed as well though issue 3 should be fixed and dev issue 1 should be referenced in the docs instead of linking to that wiki page
https://github.com/certbot/certbot/wiki/letsencrypt-auto-test-plan can be removed since there should be letsencrypt-auto instructions in the rsts
https://github.com/certbot/certbot/wiki/Links is useful
https://github.com/certbot/certbot/wiki/Plugins should be folded into rst docs
https://github.com/certbot/certbot/wiki/Releases-and-packaging should be folded into docs, also the link in the docs is broken?
https://github.com/certbot/certbot/wiki/Things-to-know-about-contributing is out of date and could be scrapped?
https://github.com/certbot/certbot/wiki/Web-Hosting-Supporting-LE might want to migrate to a pinned thread on the community forums https://community.letsencrypt.org/

[SwartzCr]

Note that https://community.letsencrypt.org/t/list-of-client-implementations/2103 links to the wiki plugins page and should be updated if it moves

[DavidBruchmann]

as newbie (haven't installed yet letsencrypt / certbot) I want to add that it might be confusing where to use "letsencrypt" and where "certbot", it starts with the problem how to name the folder for the git-repo.
I suppose the general installation explanations are partially outdated concerning this problem.

[SwartzCr]

@DavidBruchmann we have a documentation rename branch that will land by the end of the week - can you look at it and see if the issue you mention is resolved in it? #2865

[DavidBruchmann]

@SwartzCr I saw there are several threads concerning documentation in general and I think you're all on a straight way, so I still wait a bit till I try installing certbot.
One issue I remarked in #2865 is that the link https://certbot.eff.org/docs/ is password-protected and for common users useless if the password is not mentioned anywhere, but I think the page should be public anyway.

[SwartzCr]

It will be public later this week :D

[DavidBruchmann]

Thanks @SwartzCr

[pde]

PR #2981 migrates third party plugin docs from the wiki into the reStructuredText docs.

[pde]

I've also made #2986 to get started on some critical doc fixes; @ptychomancer or @SwartzCr do either of you want to review that?

[ptychomancer]

I'm out of commission for another week. The other Peter can take a look next week, though.

[pconrad-fb]

I'm ready to dig in. I've looked through some of the list of items, and it seems like a lot of them are done (point using.rst to the certbot.eff.org instructions, making a man page, for example).

I could use a little guidance on which items are high priority and where to get started. @pde and @SwartzCr what's the best place for me to start?

[SwartzCr]

I'd say a readthrough of the installation instructions would be good, as a lot of changes happened to them very quickly right before launch.
The most relevant files are here: https://github.com/certbot/website/tree/master/_scripts/instruction-widget/templates
and they get rendered to instruction sets on the main page of https://certbot.eff.org/

[pconrad-fb]

Okay. I'll get started, and I'll let you know if I have any questions. Should I consider them accurate, but needing attention? Or are there likely to be any procedural inaccuracies?

[pconrad-fb]

I've cloned the repo locally and started making edits in vi. What do you want the review process to be like? Should I check in the small amount I've done so far, or wait until I've got more done?

[schoen]

@DavidBruchmann @ptychomancer @pconrad-fb, I was telling @SwartzCr about the post at https://community.letsencrypt.org/t/lets-make-lets-encrypt-easy-and-simple/15724/26 (which gives a lot of detail about specific things in the existing documentation that a new user found confusing or ambiguous), and he suggested that I bring it to your attention in case you might be interested in working on changes prompted by that. I was planning to do so eventually, but haven't gotten around to it yet.

[bmw]

@pconrad-fb, I think it's probably best to send small PRs when you get finished pieces and we can try to review these rapidly.

[pconrad-fb]

@bmw Will do. Likely won't make more progress before my imminent PTO, so the first one will be late next week or early the following week. Thanks.

[DavidBruchmann]

Thanks @schoen for the link.
The comments are quite a lot but as far as I understood the command and
variable "letsencrypt" still can be used.
This is my primary concern, about the history of naming I don't have
questions and understood the shift from one name to another round about
december.
So my questions are just practical, where is what saved and which names are
used for folders, variables and commands.

Concerning the discussion if bug-fixing should be used for documentation:
if the existing documentation is sufficient apart from changed names for
anything practical important then fixing should be sufficient, else new
documents are probably required but that could be managed by a bugtracker
too I think ;-)

On Thu, Jun 9, 2016 at 1:17 AM, Peter Conrad [email protected]
wrote:

@bmw https://github.com/bmw Will do. Likely won't make more progress
before my imminent PTO, so the first one will be late next week or early
the following week. Thanks.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/certbot/certbot/issues/2938#issuecomment-224681175,
or mute the thread
https://github.com/notifications/unsubscribe/AA8-6lNR1iXhxvUkNuGhXlhK22MYpcwpks5qJwdKgaJpZM4IZO6f
.

[pconrad-fb]

@DavidBruchmann Can you provide more detail about your concerns? I want to make sure I work on the most high-value fixes.

[DavidBruchmann]

@Peter Conrad,
even I planned already long time to install letsencrypt / certbot I haven't
done it yet.
My primary concern is what you've to enter in installation or usage:
either
letsencrypt -someParameter
or
certbot -someParameter

additionally: when I clone the repo what foldername I should chose
(letsencrypt or certbot) and where I should place it.
furthermore it could be interesting to know where some things are stored
automatically even with the certificate itself it should be more or less
clear.

I have overflown the article mentioned bei @schoen but haven't checked the
current documentation yet. I expect that the docus are at least mostly
up-to-date and my concerns are probably already covered.

On Thu, Jun 9, 2016 at 11:49 AM, Peter Conrad [email protected]
wrote:

@DavidBruchmann https://github.com/DavidBruchmann Can you provide more
detail about your concerns? I want to make sure I work on the most
high-value fixes.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/certbot/certbot/issues/2938#issuecomment-224799234,
or mute the thread
https://github.com/notifications/unsubscribe/AA8-6oRAaZd9jzdcszmdUpxcuoBwfzHOks5qJ5tlgaJpZM4IZO6f
.

[SwartzCr]

So there are two main ways to get the code for certbot.
1) download the certbot-auto script from https://dl.eff.org/certbot-auto. In this case you would invoke it by running ./certbot-auto --someCommand as explained here: https://certbot.eff.org/#osx-apache
2) get it from your package manager. In which case you'd run something like apt-get install certbot, and then would invoke it from the commandline as certbot. All of these should be backwards compatible and allow you to invoke them with letsencrypt --someCommand as well to not break for people who have scripted them: https://certbot.eff.org/#debiantesting-other
You can also clone the github repo - which now will result in a certbot directory and the invocation ./certbot/certbot-auto --someCommand but could also be ./certbot/letsencrypt-auto --someCommand or get it from pypi directly which will work with both certbot and letsencrypt.
As far as where it puts certs, that will always be /etc/letsencrypt
Where the invocation scripts live doesn't matter in any meaningful way.

[schoen]

@SwartzCr was interested in another documentation issue that I've run into on the community forum. Briefly, some people with no system administration experience (in some cases, people who don't even know how to use SSH to run commands on their web servers, or who don't know whether they have root on the server or not, or who don't know whether or not they have shell access) hear that Let's Encrypt is very easy and then quickly get confused about the Certbot instructions.

A subspecies of this is people being unsure whether they're supposed to run Certbot on their PC or on their web server.

Forum posters suggest that we deal with by trying to make it clearer in the introductory materials for both Let's Encrypt and Certbot who the target audience is, making it much more apparent whether or not a given reader is in the target audience. And then the Let's Encrypt site could say something like "if you aren't familiar with administering your web server, ..." and give suggestions about using LE integration into web hosting.

The overall issue is that Let's Encrypt _is_ very easy today if you have a supported hosting configuration (whether that's through hosting provider integration where they do all or most of the work for you, or through having a configuration that's well-supported by Certbot). But some prospective users don't even know enough about their situation to determine quickly whether they have a supported configuration.

There are also some users who would be quite well-served by gethttpsforfree and zerossl, but those are manual and don't automate at all. Because of the 90-day certificate lifetimes, I'm not sure those users will end up being very satisfied; they may not enjoy repeating the process every 80 days, or may eventually forget. Maybe there's useful background information we could give about this, explaining who might want these services and the fact that they require periodic manual intervention for renewal.

[pconrad-fb]

@bmw I'm back from PTO. Is there a time we could talk by phone, Google Hangout, or another method for about 30 minutes next week?

@DavidBruchmann @SwartzCr These are exactly the issues I think I can help with. I'd love to meet with you (or exchange emails) after I talk to @bmw.

[SwartzCr]

I'm happy to chat any time next week, and can even do so insted of or with @bmw

[pconrad-fb]

Cool. I've set up a meeting with you and me, @SwartzCr. Feel free to pull in @bmw (I didn't find his email address, so I made the event modifiable; let me know if it stubbornly resists).

[ptychomancer]

@pconrad-fb can you send me the invite too?

[DavidBruchmann]

@pconrad-fb https://github.com/pconrad-fb a mail to your facebook-address
wasn't possible.

On Sat, Jun 18, 2016 at 12:11 AM, ptychomancer [email protected]
wrote:

@pconrad-fb https://github.com/pconrad-fb can you send me the invite
too?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/certbot/certbot/issues/2938#issuecomment-226826659,
or mute the thread
https://github.com/notifications/unsubscribe/AA8-6rAKevxA7SxVFLbePrvVhb9AEx0Hks5qMtUngaJpZM4IZO6f
.

[pconrad-fb]

Ah yes. I need to update my git info. I haven't used git in a number of
years. Sorry about that. I'll take care of that today.

Peter

[pconrad-fb]

@ptychomancer What's your email address? I'll add you.

[ptychomancer]

@pconrad-fb This is Salesforce Jason :)

[pconrad-fb]

Ha ha ok. There you go.

[SwartzCr]

During my call with @pconrad-fb I was reminded about all the things that are weird with our setup and git, so I'm going to attempt to write them all up.
The files that control the instruction generator (https://certbot.eff.org/) are located in the certbot/website repository at: https://github.com/certbot/website/tree/master/_scripts/instruction-widget
The files that control the documentation (https://certbot.eff.org/docs/) are located in the certbot/certbot repository and get automagically pulled into the website when it's deployed: https://github.com/certbot/certbot/tree/master/docs
Since none of you will have write permissions for either of these repositories, you'll have to go through the work flow of:

• Creating a personal fork of the repo - associated with your github account - for both of these repositories (certbot/certbot and certbot/website)
• Clone both of these to your local machine
• Make local changes
• Push these local changes up to your github tracked fork (git push --set-upstream origin my_new_branch_name)
• Make a pull request from your fork's branch to the appropriate master branch (e.g. certbot/certbot:master)

Then we'll review those changes, comment on them, and merge them when they look good. I also strongly suggest making different local branches for each of these changes, so that as we comment on certain change sets you can edit them without preventing other changes from getting merged.

[bmw]

One of our contributors showed us this which is generated from this and seems pretty nice. We should perhaps refer to this when cleaning up our developer instructions.

[bmw]

Just created an #3237 which mentions a specific problem in our documentation I think should be changed.

[SwartzCr]

@pconrad-fb @ptychomancer want to schedule a day to get together and co-work on some documentation? I think that'd be a good solution - I could answer factual questions and you could point out inconsistencies or things that need clarifications and offer recommendations for clean-up. Would some day next week work for you both?

[pconrad-fb]

That could work. Thursday is good for me. I was hoping to tackle some of my
list tomorrow... meaning that if I work until I get stuck I will have some
questions ready for next week (although email is good for questions too, I
trust).

Peter

On Wed, Jul 6, 2016 at 4:45 PM, Noah Swartz [email protected]
wrote:

@pconrad-fb https://github.com/pconrad-fb @ptychomancer
https://github.com/ptychomancer want to schedule a day to get together
and co-work on some documentation? I think that'd be a good solution - I
could answer factual questions and you could point out inconsistencies or
things that need clarifications and offer recommendations for clean-up.
Would some day next week work for you both?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/certbot/certbot/issues/2938#issuecomment-230940624,
or mute the thread
https://github.com/notifications/unsubscribe/AAKFbiA17v5YM5uKBsZVe8Fo8grvn_LGks5qTD41gaJpZM4IZO6f
.

[SwartzCr]

great, let's do next Thursday - is there a place we could all get together? I'm happy to offer the EFF office for this, but I could also travel somewhere if that would be more convinient

[ptychomancer]

I could see about booking us a conference room at Salesforce. Otherwise, if we want access to other EFFers, we can come to your office.

@SwartzCr

[pde]

Review and polish our FAQs, wherever they're living? Eg #1741

[SwartzCr]

we have some documentation changes that have sprouted Merge conflicts recently, I plan to go through them and get them ready for merging this week, please point me to any in progress changes that should get included as well (I know @pconrad-fb has an outstanding merge)

[pconrad-fb]

So I'll hold off then. I was going to try to merge my changes today or
tomorrow. Let me know if you need any help.

[SwartzCr]

@pconrad-fb please try to merge yours - or at least fix up the conflicts so that I can review your change. No need to wait to do that

[pconrad-fb]

Okay, will do.

Peter

Peter Conrad

Staff Technical Writer: Infrastructure | salesforce.com

Office: [phone]

[image: http://www.salesforce.com/signature]
http://www.salesforce.com/signature

On Thu, Aug 11, 2016 at 11:17 AM, Noah Swartz [email protected]
wrote:

@pconrad-fb https://github.com/pconrad-fb please try to merge yours -
or at least fix up the conflicts so that I can review your change. No need
to wait to do that

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/certbot/certbot/issues/2938#issuecomment-239245300,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAKFbqtn1x718j9iMPDaoBr7peRdsrzlks5qe2dFgaJpZM4IZO6f
.

[pconrad-fb]

Okay, conflicts resolved. I think things look pretty good. What do I need
to do, if anything, to resubmit that pull request?

Peter

Peter Conrad

Staff Technical Writer: Infrastructure | salesforce.com

Office: [phone]

[image: http://www.salesforce.com/signature]
http://www.salesforce.com/signature

On Thu, Aug 11, 2016 at 2:30 PM, Peter Conrad [email protected]
wrote:

Okay, will do.

Peter

Peter Conrad

Staff Technical Writer: Infrastructure | salesforce.com

Office: [phone]

[image: http://www.salesforce.com/signature]
http://www.salesforce.com/signature

On Thu, Aug 11, 2016 at 11:17 AM, Noah Swartz [email protected]
wrote:

@pconrad-fb https://github.com/pconrad-fb please try to merge yours -
or at least fix up the conflicts so that I can review your change. No need
to wait to do that

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/certbot/certbot/issues/2938#issuecomment-239245300,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAKFbqtn1x718j9iMPDaoBr7peRdsrzlks5qe2dFgaJpZM4IZO6f
.

[bmw]

@pconrad-fb, you don't need to do anything. Your pull request was automatically updated when you pushed the change to GitHub.

[pconrad-fb]

Awesome. Thanks.

Peter

Peter Conrad

Staff Technical Writer: Infrastructure | salesforce.com

Office: [phone]

[image: http://www.salesforce.com/signature]
http://www.salesforce.com/signature

On Thu, Aug 11, 2016 at 5:26 PM, Brad Warren [email protected]
wrote:

@pconrad-fb https://github.com/pconrad-fb, you don't need to do
anything. Your pull request was automatically updated when you pushed the
change to GitHub.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/certbot/certbot/issues/2938#issuecomment-239332322,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAKFbopJlrPmEIUXsf_t12URw1QnMfYSks5qe720gaJpZM4IZO6f
.

[SwartzCr]

Great - I've merged it and updated the website appropriately!
Do you have anything you'd like to work on next? Do you know if @ptychomancer or anyone else from SalesForce is planning on working on other parts of the documentation? If so we can help direct you

[pconrad-fb]

I would certainly be open to doing more work on these docs. What's the next priority?

[SwartzCr]

@pconrad-fb would you have any interest in taking this on: https://github.com/certbot/website/issues/158

[pconrad-fb]

Sure. Seems like a discrete and interesting project. What's the best way for me to learn about the issue?

[SwartzCr]

I'm going to close this issue since we have achieved all of the initial goals for this.
People contributing to documentation are now involved in separate more specific issues about documentation. If anyone notified by this issue's closure wants to continue to work on documentation - feel free to ping me and I can point you at useful issues. Alternately the 'documentation' tag is a good place to find issues!