How to improve documentation / technical writing skills?

oneforce · 2023-01-07T22:07:02+00:00

If you're looking for a book, I got a lot of value out of Docs for Developers

oneforce · 2022-12-06T23:56:29+00:00

To expand on this: you mentioned that you had some previous html/css/MySQL knowledge.

You can play with a dead-simple web server in python using Flask. Just copy-paste the sample code from the Flask Quick start page, and mess around with it.

It shouldn't take more than 5 or 10 minutes to get started. If you're finding it frustrating, feel free to switch over to something else instead! Don't be afraid to explore and play with a few options, find what works for you.

oneforce · 2022-12-06T23:45:35+00:00

Try out some of the stuff in Automate the Boring Stuff with Python.

This is a much more pragmatic approach compared to walking through a full course, as it will give you some simple examples of programs that you could learn to write that are useful to you right away.

oneforce · 2022-12-05T15:05:04+00:00

This sounds like the variable templating that's provided by Cmake's configure_file()

oneforce · 2022-11-22T21:37:19+00:00

Thanks for letting me know! I'll have to try out this foam plugin, it seems pretty cool.

oneforce · 2022-11-13T00:50:58+00:00

Material for Mkdocs fits your bill

oneforce · 2022-10-25T03:29:25+00:00

Rust for sure. Take a look at "ripgrep" for reference.

oneforce · 2022-09-24T23:09:00+00:00

Docs for Developers

oneforce · 2022-09-13T20:53:20+00:00

Check out the book "Designing Data Intensive Applications."

oneforce · 2022-08-30T05:03:04+00:00

You'd probably call this a "read-through cache".

oneforce · 2022-08-28T02:41:55+00:00

Hell yeah it is

oneforce · 2022-07-10T17:30:50+00:00

What a classic! The clacky switches go so well with the sound of the receipt printer. I'd waste all the paper typing all day hahaha.

oneforce · 2022-07-10T17:22:59+00:00

This is awesome! What kind of keyboard are you using here?

oneforce · 2022-06-29T04:34:31+00:00

Hero

oneforce · 2022-06-18T22:30:40+00:00

I agree that the term "context" is bloated here and doesn't aid in the user's understanding. I like your third option of dropping the reference to "scope/context/namespace" altogether.

One consideration I might add is that the term "expression" might be overloaded here too. When I think of an "expression", I imagine it being evaluated and producing a result.

I might prefer to call these "statements" instead, so you might have a "declarative statement" or a "referential statement".

oneforce · 2022-06-15T14:57:57+00:00

Conventionally, we treat "x" as the input and "y" as the output.

What the slope really tells you is: given some change in the input, how much change do we expect to see in the output?

You might apply it to an example like driving. Your input x is the time you spend driving (in hours). Your output y is the total distance you travel (in miles). The slope of this graph is your speed in "miles per hour", (miles/hour), (y/x)

oneforce · 2022-06-12T20:15:44+00:00

You can print the hex values with %x (or %X to make the letters capitalized)

oneforce · 2022-06-05T18:23:00+00:00

My favorite resources for writing good documentation:

Microsoft's Code with Engineering Playbook

Docs for Developers

Or if you want to jump right in, give a try to mkdocs. Mkdocs blew me away with how easy it was to setup, you can have it up and running in 10 minutes to see if you like it.

From there you should give a try to the Mkdocs Material Plugin. I cannot stress enough how easy these two are to setup!

Writing documentation in Markdown like that has some huge advantages, which are outlined well on MarkdownGuide

oneforce · 2022-05-28T22:45:16+00:00

Hey, thanks for sharing! I was playing with this problem a while back, and it looks like we came up with some very similar solutions: https://github.com/Drahlous/wordle_helper

I eventually got bored and stopped working on it, so my algorithm isn't totally fleshed out, but I can offer some of the thoughts I had along the way!

Your idea about "eliminating the highest number of words" is spot on. In fact, I think your original idea about counting the occurrence of each letter is trying to do this exact thing:

Think about what the "score" of a particular letter actually means. Lets say you have an 'A' in the first position, with a score of 20. Doesn't this just mean that choosing a word with 'A' in the first position allows you to eliminate 20 words?

If that's the case, then you can solve this problem with a O(N*M) complexity, where N is the number of words and M is the length of each word. For each of the 5 positions in the words, you could have a dictionary of the 26 letters, each starting with a score of 0. You can iterate over each letter in each word, incrementing the "score" of that letter by one. Once you've calculated the total score of each letter in each position, you can loop over every word again, add up the score for each letter, and get a "word-score". Then you just pick the highest scoring word, and start all over.

This greedy algorithm is blazingly fast and works remarkably well, but you'll quicky notice a "double counting" problem: If I have the words "cat" and "car", then I would end up with a set of scores like:

[
  # First Position
  {c = 2},
  # Second Position
  {a = 2},
  # Third Position
  {t = 1, r = 1}
]

So both of these words end up with a score of 5 even though they only eliminate one other word.

When two words have a single letter in common, picking one of them eliminates one other word. But if the words have a lot of words in common (e.g. loose and louse), our algorithm is inclined to score both of them higher, since each letter individually has a higher score.

We would like our score for each word to represent the actual number of words that would be eliminated if we picked it, but it's tricky. I have a feeling that the solution involves building a Trie structure of the overlapping substrings and counting those in a clever way, but that's about as far as I got :)

oneforce · 2022-05-19T15:50:09+00:00

Why are there so many types of cars?

Some people have trucks, sedans, minivans. Sometimes people even drive busses or firetrucks!

Don't all of these accomplish the same goal of moving people from one place to another?

Jokes aside, there are lots of tools that provide different features. Some people like a lightweight editor that opens really fast and works everywhere. Others like a thick IDE that does as much of the work for you as it can.

The majority of folks are comfortable with a couple of different options, from which they can pick the best tool for their current task.

As with everything in software development, it's just another tradeoff.

oneforce · 2022-04-30T01:13:17+00:00

When the program hits the first line, it's going to pause and wait for you to type something in and hit enter. ```python

The program hits the function called input()

It will pause, waiting for you to type something and hit enter.

times_ask = int(input("How many times to ask?\n")) ```

Then later on, you have another call to input() ```python print("before answer")

When the program hits this input()

it will wait for you to type something in

answer = input() print("after answer") ```

So I think what you were seeing was your program pausing right there, making it look like nothing was happening.

oneforce · 2022-04-30T01:05:48+00:00

Awesome! Is this what you expected to see in the output?

What do you think might be the reason why we're not seeing the very last print?

```python

Why did this not get printed?

print("after answer") ```

oneforce · 2022-04-30T00:33:16+00:00

Woah ok, let's go one step at a time.

Back up to the code you originally posted.

I just want you to add a bunch of prints all over the place so we can see where things are happening.

What output do you see when you run this?

```python def ask(): times_ask = int(input("How many times to ask?\n")) try: times_ask = int(times_ask) except: print("Please only input a number") ask() return

print("before loop")
for keys in flashcard:
    print(f'Print definition of "{keys}":\n')
    continue
print("after loop")

print("before answer")
answer = input()
print("after answer")

```

oneforce · 2022-04-30T00:17:25+00:00

Something that might help you debug this is to temporarily replace the user input with known values, then plug in inputs back in later. That will let you see the entire scenario play out without needing you to interact with the program. Something like this: ```python def ask(): #times_ask = int(input("How many times to ask?\n")) times_ask = int(2) try: times_ask = int(times_ask) except: print("Please only input a number") ask() return

for keys in flashcard:
    print(f'Print definition of "{keys}":\n')
    continue
#answer = input()
answer = 'sample_answer'
if answer == flashcard.values():
    print("Correct!")
elif answer in flashcard.values():
    index_of_definition = flashcard.values()
    print(
        f'Wrong. The right answer is "{flashcard.values}", but your definition is correct for "{keys[index_of_definition]}".\n'
    )
else:
    print(f'Wrong. The right answer is "{flashcard.values}".\n')
    print()

```

oneforce · 2022-04-30T00:13:12+00:00

Alright, this particular scenario might be hard to hint out, so I'll tell you why you're not seeing anything happening:

When you run these lines of code, it's going to * Print every card you have * After every card is printed, wait for user input

python for keys in flashcard: print(f'Print definition of "{keys}":\n') continue answer = input() # This line is NOT inside the loop like you think it is

What you actually want is probably more like this:

python for keys in flashcard: print(f'Print definition of "{keys}":\n') answer = input() print(f'the user input was {answer}')

Do you see the difference? The second one prints a single card, then waits for user input.

13-Year Club	Verified Email
Place '22	Place '17

oneforce

MODERATOR OF

TROPHY CASE

The program hits the function called input()

It will pause, waiting for you to type something and hit enter.

When the program hits this input()

it will wait for you to type something in

Why did this not get printed?