Keep track of the key issues arising in the reading group

[holtzermann17]

Issue #1 proposes a general and long term approach to tracking issues. It suggests a technical approach. We could get there eventually but let's re-focus on something immediately practical here.

This issue, #3, is about extracting as much as we can from the Augment notes:

1. If we have small-scale changes, we can implement them directly (possibly copying over text from Augment's Google Docs). But we should still try to keep track of what changes we've made so that we don't replicate them. We can use this issue tracker for this (maybe one issue per article that we change).
2. If there are bigger or more comprehensive stylistic changes, then it's not just a matter of local changes. We could therefore use the issue tracker to work on an improved "style guide" that describes the changes we have made, and helps ensure that future edits don't repeat old mistakes. I suggest, therefore, that a short writing guide will be on of the main outcomes of the reading group. I will find and check in our current best effort, and we can improve it together.

[skreutzer]

That's the cost now of not doing the changes and suggestions to the actual authoritative text that's intended to be the source for the handbook version 4, but onto a separate copy instead (why so in the first place?). I'm not planning to simply duplicate the effort and waste scarce lifetime for no good reason.

That said, Google Docs has some exports, which may help to better figure out what was changed where, maybe extract change suggestions too, and maybe supporting a better way to review and check off the mess of comments. Try to build some tools to help with that? Invest the time for tooling + for the non-reducable manual work of review and merging, or do it all by brute force? Who's volunteering? :-) Especially as the reading group would need roughly the same amount of time (or more) for cleaning up and curation as it took for reading sessions, with all the material scattered, and without new sessions, who's going to look back at records of past events, in which change suggestions to the handbook are the minority and potentially hard to identify, where it might be easier to just review/correct the handbook all over again from scratch (organized in issues per chapter with change suggestions being made onto the original, and explicitly captured/tracked)? I'm not in favor of ever loosing anything (contributions, comments), but what can you do with extra, additional entropy features built in?

Full disclosure: don't have solutions, just can't afford doing editing/curation in digital the paper book way.

[holtzermann17]

Copying changes is pretty easy, and I'm happy to do that part. The bigger challenge is to understand the difficulties that people encountered with the material, and use that to steer changes both in Version 4 and in future editions. This is where the style guide comes in. Each change we make is made for a reason, and those should be understood as well as possible and recorded. Again, I am happy to do this part too. If anyone would like to join in these activities they can, if not, other good uses of time include writing other new articles or tackling any of the other explicit issues that we've accumulated so far!

[daytripper]

Joe, I would be happy to help you on that.

On Sat, Dec 21, 2019, 8:46 AM Joe Corneli notifications@github.com wrote:

Copying changes is pretty easy, and I'm happy to do that part. The bigger challenge is to understand the difficulties that people encountered with the material, and use that to steer changes both in Version 4 and in future editions. This is where the style guide comes in. Each change we make is made for a reason, and those should be understood as well as possible and recorded. Again, I am happy to do this part too. If anyone would like to join in these activities they can, if not, other good uses of time include writing other new articles or tackling any of the other explicit issues that we've accumulated so far!

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/Peeragogy/ReadingGroup/issues/3?email_source=notifications&email_token=AAZPUMZL3EDISMWYLDVHICLQZYM4LA5CNFSM4J3JET62YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEHO4L6Y#issuecomment-568182267, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAZPUM4NNGDRINPCOBLRMILQZYM4LANCNFSM4J3JET6Q .

[rolandlegrand]

I'd like to rewrite whole sections of the book as patterns. I guess the best way to try this (I'm not sure it will succeed) is by forking?

[skreutzer]

@rolandlegrand I can try to provide technical assistance, if needed. Generally speaking, the patterns are in the https://github.com/Peeragogy/Peeragogy.github.io repository, the file names start with "pattern-" and end with ".md". These raw plain text files contain Markdown to structure the text according to the pattern template, and then semantic or formatting instructions for generating the website and PDF. I think adding new files like this would best be done by indeed forking this repository to your own GitHub profile, then adding new pattern files to your copy, then create a pull request (to merge your copy into the Peeragogy one). The main reason for this (and not working on the current live Peeragogy repository) is that some additional work is needed so new pages go live (live in terms that commits in a few minutes get automatically updated/reflected/published on the Peeragogy GitHub Pages website) on the website and are integrated into the PDF generation. But you can also try to do this yourself, which would be even better :-) Another reason to use forks is that for committing/publishing directly to the live repository of the Peeragogy GitHub group, you need to be member and have permission, but forks and pull requests always work without the need to get cooperation/setup with the source repository in advance.

There's also the option to do it outside of git, as the git repository is just for publishing/organizing these files and their revisions, so if it's too tedious to use git/GitHub, changes could be added in bulk manually later, which isn't ideal of course, but the whole git/GitHub thing in its current form isn't particularly helping either. One big requirement would be to stick to Markdown, otherwise converting formats manually could lead to some trouble and additional unnecessary work which could have been saved in the first place. Normally we would implement the pattern template in software, and that would automatically generate the corresponding Markdown to be submitted to GitHub, so there wouldn't be a need for authors to mess with any of the Markdown at all, but concentrate on the writing and text work.

There's also a separate repository https://github.com/Peeragogy/PHVersion4-RAW which seems to be for collecting new materials for the version 4, but it might be mostly abandoned, and why work in separate other repositories and not on the real, actual one, but in forks/branches, so there's less work later to integrate/merge the new material, and it's already available to generate PDFs from the many individual/custom forks/branches?

Patterizing existing texts could be a separate GitHub issue (in this ReadingGroup repository or better at the actual source repository, https://github.com/Peeragogy/Peeragogy.github.io/issues) as this issue is about coming up with ways for tracking activity. Or one issue there per non-pattern source chapter.

In general, if we would have the capacity and want/need/interest to build software for managing pattern catalogs, these tasks would benefit a lot from tool assistance, but at this point, we still have to do these Gutenberg style, which is manually, by hand.

[holtzermann17]

I agree with most of what was said thank you. Just to add that creating a fork is a good way to go, and making changes directly to the files that are being patternized in the fork might be one good option.

If you want an even more informal way to work before getting started with this, one option that occurs to me would be to ride in the wiki that is attached to one of these repositories. Since the wiki uses mark down and is it self a get repository, it will be easy to merge work there into the repo at a subsequent later date. But yeah anything that goes into the handbook should be done via pull request eventually. However, don’t let that slow you down regarding getting started with some other way to work at first! Just pick which ever is comfortable and share it and then we can help you with the technical details if needed.

Starting with one example, we can refine and scale up.

[holtzermann17]

One way to manage the issues is to turn them into projects.

Let's do that here: https://github.com/orgs/Peeragogy/projects/1

Ideally we can have a few but not too many tickets per project. I'd also like to spec out my Nesta project this way, so I might try that as a starter example.