search

beanstalkd / beanstalkd.github.io

Beanstalkd's website.
https://beanstalkd.github.io/
1 stars 2 forks source link

Protocol description as a PDF #12

Open petri opened 4 years ago

petri commented 4 years ago

Attached. Add to the web page?

Beanstalkd.pdf

ysmolski commented 4 years ago

@petri thank you for doing this. By any chance, was this conversion automatic? I would like to understand how could we maintain (edit) the pdf in the case when we change protocol.

petri commented 4 years ago

No, fully manual. The master source is Apple Pages. Besides uploading that, I could generate an EPub version as well, and whatever else it exports. I just wanted to try creating a full technical document in Pages and thought I'd contribute this. But apart from easy PDF & EPub creation, it's not that great for other than simple things.

I'd guess it'd be best to just improve the protocol description so it uses conformant ReStructuredText or MarkDown. Could then use Sphinx or MkDocs, or whatever tool. Greenstalk has already some Sphinx docs, and some other clients maybe as well.

kr commented 4 years ago

At the risk of asking a stupid question, what are the drawbacks of using ASCII for this document, and what are the benefits of producing a PDF? Do those benefits outweigh the cost of adding the necessary additional tools as beanstalkd build dependencies?

petri commented 4 years ago

Cost/benefit questions are always relevant I guess. But for the benefit of the project, perhaps it's more useful to ask:

  1. could and should the developer (protocol) docs be improved?
  2. if so, what's the best way to have some sufficiently improved outcome?

I guess for an open source project, 1) is always a yes if there's someone willing to do it?

As for 2), besides improving the content itself, there's many ways to manage the docs, and not all of those require adding tools to core beanstalkd build process.

By the way, might be a good idea to explicitly mention somewhere that the protocol doc is written in asciidoc or syntax very near it. Renders nice with https://asciidoclive.com . Or is that documented somewhere already?

kr commented 4 years ago

I guess for an open source project, 1) is always a yes if there's someone willing to do it?

In my experience it is not always true that someone will have the time and willingness to do extra work.

Don't forget, adding more tool dependencies incurs ongoing maintenance burden, it's not just a one-time cost.

As for 2), besides improving the content itself, I think it's safe to say that an industry-standard source format […]

If standardization is the main criterion for choosing a documentation format, I would argue that ascii is more established as a standard than ReST or markdown (or pdf, for that matter).

kr commented 4 years ago

By the way, I'm not trying to be dismissive, I also really do appreciate the work you already put in to this.

I think pdf is a reasonable format, and I think ascii is too. Having already chosen one reasonable format, some hysteresis is appropriate. It's not enough to say "this other format is reasonable too" or even "this other format is marginally better". The new format needs to be significantly better and there should be evidence that the additional benefit is worth the additional cost.

petri commented 4 years ago

Just to be clear, my intent, when posting this issue, was not to sell some idea of e.g. dropping ASCII protocol doc in favor of PDF.

I shared the PDF version of the doc I had created because it is, to me, more useful than the original source, and wanted to offer others the possibility of gaining the same benefit. That's all. If some do, great, if not, that's fine.

That being the case, I was not considering any long-term source format, build or maintenance implications. While I offered here, when asked, some suggestions that relate to those, I don't have time available to me to convince anyone or build evidence for some particular or possible choices about them. Nor do I really want to. Not meaning to be dismissive of any need or requirement that any individual, the project or the maintainer community might have for those. Thus also accepting the possibility of the doc then just ending up buried here.

If there will be any need for the original document source version, let me know and I'll be happy to submit it.

alrik11es commented 1 year ago

I am in favor of the proposed PDF file format. Additionally, I believe that the original file could be further enhanced with the implementation of markdown styling. Overall, I am supportive of multiple formats, as it allows for maximum accessibility and inclusivity for all audiences.